home *** CD-ROM | disk | FTP | other *** search
/ Deutsche Edition 1 / Deutsche Edition 1.iso / amok / 081-090 / amok89 / headerinfo < prev    next >
Text File  |  1993-11-04  |  12KB  |  337 lines
  1. ===========================================================================
  2.                AMOK - Amiga Modula & Oberon Klub  Stuttgart
  3.  
  4.                      Standard Identifier für ProgInfo
  5.                (Dokumentationsextraktion aus dem Quelltext)
  6. ===========================================================================
  7.  
  8. Programmkopf
  9.  
  10. Für  alle  AMOK-Programme  ist  ein  Programmkopf  vorgeschrieben,  der die
  11. wichtigsten Informationen zu diesem enthält.
  12.  
  13. Bei  Modula-2-  bzw.  Oberon-Programmen muß er vor dem Schlüsselwort MODULE
  14. in  einem  Kommentar  stehen.   Er  sollte  durch  "***"- oder "---"-Zeilen
  15. hervorgehoben  sein,  ein  Einrahmen  ist  jedoch  nicht zweckmäßig (da die
  16. letzten "*"s in der Zeile stören).
  17.  
  18. Der    Programmkopf    enthält    mehrere   Einträge,   die   jeweils   mit
  19. ":"Schlüsselwort"."  beginnen.   Reicht  eine Zeile für einen Eintrag nicht
  20. aus,  wird das ":"Schlüsselwort"." in der nächsten Zeile wiederholt und der
  21. Eintrag  danach  fortgesetzt.   Doppelpunkt,  Punkt  und  Schreibweise sind
  22. wichtig,   da  sonst  die  Einträge  von  Doku-Extraktionsprogrammen  nicht
  23. gefunden werden.
  24.  
  25. Der Programmkopf muß (!) mindestens folgende Einträge enthalten:
  26.  
  27. :Program.       <Programmname>
  28. :Contents.      <Kurzbeschreibung von Inhalt/Verwendungszweck>
  29. :Author.        <voller Autorenname, kein Pseudonym (!)>
  30. :Copyright.     <Copyright-Bestimmungen des Moduls>
  31. :Language.      <Sprache, eventuell Bemerkung über Besonderheiten>
  32. :Translator.    <Name des Compilers/Assemblers mit Versionsangabe>
  33. :History.       <Version, Autor, Datum, Bemerkung>
  34.  
  35. Falls notwendig müssen auch folgende Angaben gemacht werden:
  36.  
  37. :Support.       <Hinweis auf von anderen übernommene Programmteile/Ideen>
  38. :Imports.       <Importierte Module außer dem Standardumfang des Compilers>
  39. :Bugs.          <bekannte Fehler>
  40.  
  41. Freiwillig sind diese Angaben:
  42.  
  43. :Address.       <Adresse des Autors>
  44. :Phone.         <seine Telephonnummer>
  45. :Update.        <Angaben über Änderungen, die :History. nicht abdeckt>
  46. :Remark.        <beliebiger Kommentar>
  47. :Usage.         <Usage zB. für CLI-Befehl>
  48.  
  49. Andere Einträge, Date, Shortcut, Version sind nicht mehr zu benutzen!
  50. Fehlende  Einträge  sollten  so  bald und gut als möglich nachgetragen oder
  51. rekonstruiert werden.
  52.  
  53.  
  54. Empfehlungen
  55.  
  56. Auf eine strikte Festlegung des Programmkopftextes wurde verzichtet.  Damit
  57. dieser  jedoch  einigermaßen  einheitlich  bleibt  sollte man die folgenden
  58. Regeln beachten.
  59.  
  60. Leere Einträge
  61.  
  62. Außer  den  zuerst  genannten Pflichteinträgen können eventuell auch welche
  63. entfallen.   Am besten läßt man dann den gesammten Eintrag sammt Schlüssel-
  64. wort  weg.   Als  leer  gelten  außerdem Einträge, die nur aus Leerzeichen,
  65. Sternchen "*" oder Strichen "-" bestehen.
  66. Unsinnige Einträge (zB.  ":Imports.  bis jetzt noch nichts") sind möglichst
  67. zu unterlassen.
  68.  
  69. :Program.
  70.  
  71. Hier  sollte der Programmname stehen, der mit dem Filenamen (mit Extension,
  72. zB.   "Test.def")  übereinstimmen  sollte.   Reicht  der  Programmname  zur
  73. eindeutigen Indentifizierung nicht aus (zB.  geändertes Modul "Strings") so
  74. steht hinter dem Programmnamen ein entsprechender Kommentar.
  75.  
  76. :Contents.
  77.  
  78. Kurzbeschreibung von Programminhalt und -funktion.  Die Beschreibung sollte
  79. erklärend sein und nicht nur eine längere Version des Programmnamens sein
  80. (zB.  N I C H T :
  81.  :Program.  InOut.def
  82.  :Contents. Definitionsmodul Input/Output
  83. ).
  84.  
  85. :Author.
  86.  
  87. Bitte den vollen Namen angeben. Pseudonyme sind unzulässig.
  88. Ein  Programm kann auch mehere Autoren haben, zB.  wenn ein PC-Programm auf
  89. den AMIGA umgesetzt wurde.
  90.  
  91. :Address.
  92.  
  93. Freiwillig  ist  die  Angabe  der  Adresse  des Autors.  Sie sollte Straße,
  94. Hausnummer, Postleitzahl, Ort und Land enthalten.
  95.  
  96. :Phone.
  97.  
  98. Telefonnummer  des Autors mit Vorwahl.  Zusätzliche Bemerkungen, zB.  Zeit-
  99. angaben für Erreichbarkeit, sind zulässig.  Hat ein Programm mehere Autoren
  100. (siehe  oben)  so  steht  hier  die  Telefonnummer  des für dieses Programm
  101. zuständigen  Autors,  d.h.   desjenigen,  der  eventuelle  Fragen am besten
  102. beantworten kann.
  103.  
  104. :Copyright.
  105.  
  106. Hieraus  sollte  ersichtlich  sein, ob das Programm Freeware oder Shareware
  107. ist oder ob auf alle Rechte verzichtet wird (Public Domain).
  108.  
  109. Freeware:
  110. - Der Autor legt die Kopierbestimmungen fest und
  111. - behält alle Rechte an seinem Programm
  112.  
  113. Shareware:
  114. - Der Autor legt die Kopierbestimmungen fest
  115. - behält alle Rechte an seinem Programm und
  116. - erhebt bei regelmäßigem Gebrauch eine anerkennende Gebühr
  117.   (Shareware-Gebühr), die gezahlt werden MUSS!
  118.  
  119. Kommentare  wie  zB.   "copy  it, but leave my name in" oder ähnliches sind
  120. zulässig.   Bei längeren "Plädoyers" sollte allerdings auf eine extra Datei
  121. verwiesen werden.
  122.  
  123. :Language.
  124.  
  125. Hier  steht  im  Normalfall  "Modula-2"  bzw.  "Oberon".  Wenn das Programm
  126. INLINE-Assemblercode  enthält,  sollte  dies  hier Vermerkt werden.  Ebenso
  127. sollte  verfahren  werden,  wenn  das  Programm  dem  Modula-Standard nicht
  128. entsprechende  Statements  enthält.   Dazu  gehört  unter  anderem die seit
  129. M2Amiga   v3.2   mögliche   Typenkonversion   von   ADDRESS/BPTR   und  die
  130. Dereferenzierung  von  BPTRn  (Zugriff  auf  BcplPtr^.items).   Die normale
  131. Verwendung  des  Typs BPTR als opaker Typ gehört nicht dazu, denn er ist im
  132. Standard-Modula  erlaubt.   Der  Sinn  hiervon ist es, Leute zu warnen, die
  133. Programme auf andere Compiler umsetzen wollen.
  134.  
  135. :Translator.
  136.  
  137. Bezeichnet  den  Compiler  (/Assembler/Interpreter)  und die Versionsnummer
  138. (v1.17  oder v2.0).  Dahinter stehen eventuelle Hinweise auf Compiler-Bugs,
  139. die für dieses Programm relevant sind.
  140.  
  141. :History.
  142.  
  143. Dies  ist einer der wichtigsten Einträge.  Er beinhaltet Informationen über
  144. die  Versionen  des  Programms (Opfer), der entsprechenden Erstellungs- und
  145. Änderungsdaten  (Tatzeit),  den Autor oder für die Änderung Veratwortlichen
  146. (Täter) sowie eine optionale Bemerkung (Motiv).  Beispiel:
  147.  
  148. :History.       v1.1 [bne] 29-Mar-89 bug in Init() fixed
  149.  
  150. Den  Versionsnummern  wird  später  noch  ein  spezielles Kapitel gewidmet.
  151. Zusammengehörige   Definitions-   und  Implementationsmodule  tragen  immer
  152. mindestens   gleiche   Versionsnummer  (Revisionsnummer,  Branchnummer  und
  153. Kennbuchstabe dürfen verschieden sein).
  154. Das  Datum  besteht  aus  dem ein- oder zweistelligen Tag, dem Monatskürzel
  155. (Jan,Feb,Mar,Apr,May,Jun,Jul,Aug,Sep,Oct,Nov,Dez)  aus  drei Buchstaben und
  156. der  zwei  oder  vierstelligen  Jahreszahl.   Für den Autor steht sein Name
  157. Klammern (für Klubmitglieder das Kürzel).
  158.  
  159. :Support.
  160.  
  161. Der  Fairneß  halber sollte man hier Angaben über Beiträge anderer Personen
  162. sowie deren Namen machen, wenn man Schuldgefühle wegen geklauter Ideen oder
  163. Algorithmen hat.
  164.  
  165. :Imports.
  166.  
  167. Importiert  das Modul außer den Standardmodulen des Compilers noch weitere,
  168. so  müssen  diese  hier  eingetragen  werden.   Wird eine bestimmte Version
  169. benötigt, folgt auf den Namen des importierten Moduls dessen Versionsnummer
  170. sowie  der  Autor.   Es dürfen auch Verweise auf AMOK-Disks gemacht wedren.
  171. Beispiel:
  172.  
  173. :Imports.       MemSystem1.3 [bne], List [mif] AMOK#7
  174.  
  175. :Bugs.
  176.  
  177. Sind  Fehler eines Moduls bekannt, oder besteht der Verdacht, daß das Modul
  178. fehlerhaft ist, wird dies hier vermerkt.  Soweit dies möglich ist, soll der
  179. Fehler  möglichst eng eingegrenzt werden (zB Angabe der Prozedur, in der er
  180. auftritt).   Ist  ein  Modul noch nicht vollständig ausgetestet, sollte man
  181. mit ":Bugs.  not tested" warnen.  ":Bugs.  none" verpflichtet zu mindestens
  182. 99,9% Fehlerfreiheit!
  183.  
  184. :Usage.
  185.  
  186. bezeichnet  die  Syntax  eines CLI-Befehls und dessen Argumente.  Die Usage
  187. wird  entweder  in  EBNF  oder mit dem vom DOS-Handbuch und ARP verwendeten
  188. Template angegeben.
  189.  
  190.  
  191. Versionsnummern
  192.  
  193. Die   Versionsnummer  besteht  normalerweise  aus  zwei  Stellen  (version,
  194. revision),  die  durch  einen  Punkt  getrennt  sind.  Die erste lauffähige
  195. Version wird mit 1.0 bezeichnet.  Bei jeder Änderung wird die zweite Stelle
  196. (Revision)  um  eins  erhöht,  wobei  nach  1.9 die 1.10 und dann 1.11 usw.
  197. folgt.   Bei sehr tiefgreifenden Neuerungen wird die erste Stelle (Version)
  198. erhöht, die zweite (Revision) springt auf 0.  Die Versionsnummer darf NICHT
  199. als  Dezimalbruch angesehen werden, der sich jedesmal um 1/10 erhöht.  Eine
  200. Revision  ist  KEINE  zehntel  Version und eine Version entspricht NICHT 10
  201. Revisions.     Version    und   Revision   werden   unabhängig   gezählt!!!
  202. Versionsnummern  wie  1.09  sind unzulässig und 1.10 (erste Version, zehnte
  203. Revision)  steht  zwischen  1.9  und  1.11  und  ist  nicht  gleich  1.1  !
  204. "Hundertstel"  Versionen  gibt  es  nicht.  Wenn es erforderlich wird, eine
  205. Version nachträglich in eine Reihe einzufügen, wird dies durch eine zweiten
  206. Punkt gekennzeichnet.  Beispiel:Es existieren bereits die Versionen 1.0 bis
  207. 1.4  , und jemand ändert nachträglich die Version 1.2 .  Diese bekommt dann
  208. die  Nummer 1.2.1 (sog.  Branch-Version).  Man kann Versionsreihen auch als
  209. Baum darstellen:
  210.  
  211.       1.0
  212.  
  213.        |
  214.        V
  215.  
  216.       1.1
  217.  
  218.        |
  219.        V
  220.  
  221.       1.2
  222.  
  223.        |
  224.       / \
  225.      /   \
  226.     V     V
  227.  
  228.    1.3   1.2.1
  229.  
  230.     |      |
  231.     V      V
  232.  
  233.    1.4    1.2.2
  234.  
  235.     |      usw.
  236.  
  237.    ...
  238.  
  239.     |
  240.     V
  241.  
  242.    1.9
  243.  
  244.     |
  245.     V
  246.  
  247.    1.10
  248.  
  249.    usw.
  250.  
  251.  
  252. Die  Zählweise  entspricht  nicht der von Big Blue, verleitet aber dafür zu
  253. weniger Mißverständnissen, weil man nicht rätseln muß, ob 3.2 jetzt die auf
  254. 3.1  oder  auf  3.19  folgende  Version  ist.   Version und Revision können
  255. beliebig  hoch  werden  -  Beispiel:  die Libraries der alten 1.2 Workbench
  256. trugen    die    Versionsnummer    33.180    (dreiunddreißigste    Version,
  257. hundertachzigste Revision).
  258.  
  259. Wer  noch  eine  feiner  abgestufte  Unterscheidung machen möchte, kann der
  260. Nummer  noch  einen  Kleinbuchstaben anhängen.  Dieser ist optional und muß
  261. nichts  über  die Reihenfolge aussagen (zB.  3.2d für die deutsche und 3.2e
  262. für die englische Version).
  263.  
  264. Entsprechend  dem  Vorschlag von Bernd Preusing ist es jetzt doch zulässig,
  265. daß  ein  Implementationsmodul  eine  höhere  Revisionsnummer  hat  wie das
  266. zugehörige  Definitionsmodul.   Dadurch  ist  es  nicht  nötig, wegen jeder
  267. Kleinigkeit  das  Definitionsmodul anzutasten, wodurch das Make viel Arbeit
  268. bekäme.
  269.  
  270.  
  271. Source-Code-Format
  272.  
  273. Damit   der   Sourcecode  einigermaßen  übersichtlich  ist,  wird  folgende
  274. Formatierung vorgeschlagen (nicht zwingend, nur übersichtlich muß es sein):
  275.  
  276. * In jeder Zeile steht nur eine logische Anweisungseinheit.
  277.  
  278. * Globale  Prozeduren,  Variablen  und Konstanten stehen ganz am Anfang der
  279.   Zeile.
  280.  
  281. * Deklarationen  und  Prozedurkörper  sind gegenüber ihrem CONST, VAR, TYPE
  282.   und PROCEDURE eingerückt.
  283.  
  284. * Programmteile, die lokal zu anderen definiert werden, oder von bestimmten
  285.   Konstrukten  eingeschlossen  werden,  werden jeweils relativ zu diesen um
  286.   ZWEI Zeichen eingerückt.
  287.  
  288. * Zusammengehörende  BEGIN  und  END, IF, ELSE und END usw.  stehen jeweils
  289.   untereinander.  Ist ein END mehr als eine Bildschirmseite (25 Zeilen) von
  290.   seinem  BEGIN etc.  entfernt, steht hinter dem END in Kommentar, was dort
  291.   beendet wurde.
  292.  
  293. * Außer nach VAR, CONST, TYPE, BEGIN, DO, THEN, LOOP, RETURN und EXIT steht
  294.   hinter jeder Zeile ein Semikolon.
  295.  
  296. * Elemente  von  Mengen,  Aufzählungstypen  und  RECORDs  fangen  klein an,
  297.   Konstanten   fangen   klein  oder  groß  an,  alles  andere  immer  groß.
  298.   Zusammengesetzte Wörter haben auch in der Mitte "GrossBuchstaben".
  299.  
  300. * Paßt  die Parameterliste einer Prozedur nicht in eine Zeile (75 Zeichen),
  301.   werden die Parameter untereinander angeordnet.
  302.  
  303. * Importe  werden  alphabetisch  nach  den Namen der Module geordnet.  Sind
  304.   Importlisten  länger als zwei Zeilen werden auch die importierten Objekte
  305.   alphabetisch sortiert.
  306.  
  307. MODULE Beispiel;
  308.  
  309. CONST
  310.   welches = 106;
  311.  
  312.  
  313. PROCEDURE TuWas(Dies: Typ;
  314.                 VAR Jenes: Art): BOOLEAN;
  315.   CONST
  316.     X = 1;
  317.     Y = 10;
  318.  
  319.   VAR
  320.     Zähler : INTEGER;
  321.  
  322.   BEGIN
  323.     FOR Zähler := X TO Y DO
  324.       Action(Dies, Jenes);
  325.     END
  326.     RETURN Jenes = welches
  327.   END TuWas;
  328.  
  329.  
  330. BEGIN
  331.   IF TuWas(etwas, irgendWas) THEN
  332.     Aktion1;
  333.   ELSE
  334.     Aktion2;
  335.   END;
  336. END Beispiel.
  337.